.\"Copyright (C) 2007, 2011 Anton Zinoviev <anton@lml.bas.bg>
.\"
.\"Copying and distribution of this file, with or without
.\"modification, are permitted in any medium without royalty provided
.\"the copyright notice and this notice are preserved.  This file is
.\"offered as-is, without any warranty.
.\"
.\" Process this file with
.\" groff -man -Tascii bdf2psf.1
.\"
.TH BDF2PSF 1 2006-01-16 console-setup "Console-setup User's Manual"

.SH NAME
bdf2psf \- convert a BDF font to PSF format for the Linux console

.SH SYNOPSIS
.B bdf2psf [--fb]
.BI [--log " logfile" ]
.IB bdf {+ bdf }
.IB equivalence {+ equivalence }
.IB symbols {+[:] symbols }
.I  size psf
.BI [ sfm ]

.SH DESCRIPTION

The program
.B bdf2psf
translates BDF fonts to PSF format. It accepts fonts with arbitrary
size of the font matrix. If the width of the glyph matrix of the
source font is 7 or 9 pixels then it generates fonts with width of 8
pixels.

.SH OPTIONS

.IP --fb
Generate font for framebuffer. There are two important differences
between the framebuffer and the text mode. First, all fonts in text
mode have to have matrix 8 pixels width. They also have to have either
256 or 512 glyphs. Second, in most text modes the hardware does some
magic in order to use 8 pixels width fonts as if they were 9 pixels
width. In order to achieve this the video hardware copies the 8th
column in the 9th column of the glyphs with codes from 0xC0 to 0xDF
and from 0x1C0 to 0x1DF. 
.B Bdf2psf
is very careful when deciding where to place a particular glyph and as
a result the encoding of the generated font is more or less arbitrary.

.IP "--log logfile"
Record in the file
.I logfile
any problems during the conversion.

.IP bdf{+bdf}
The "\+"-separated list of the source BDF font(s). When a particular
symbol is defined in more than one of the specified fonts then fonts
listed first take precedence.

.IP equivalence{+equivalence}
A "\+"-separated list of files defining an equivalence relation
between the glyphs. See the section EQUIVALENCE FILES below.

.IP symbols{+[:]symbols}
A "\+"-separated list of files describing character sets.  The
generated font will support all specified character sets.  When there
is no space in the PSF font for all symbols, the character sets listed
first take precedence.  When a colon before a character set is
specified no warnings will be issued for symbols that could not be
placed in the font. See the section CHARACTER SETS below.

.IP size
The size of the PSF font. Usually 256 or 512 glyphs.

.IP psf
The name of the generated font.  If a file with this name already
exists it will be overwritten.

.IP sfm
Save in the file
.B sfm
the SFM of the generated font. This parameter is optional.

.SH CHARACTER SETS

The encodings of the traditional console fonts a similar to the
standard encodings of the different languages.  For example there are
fonts for all variants of ISO 8859.  This is redundant, for example
ISO 8859-1, ISO 8859-9 and ISO 8859-15 differ only by few characters
and can be easily covered by only one font.

In order to determine the minimal set of character sets a clustering
algorithm has been used. The source code of
.B fontconfig
contains lists of the characters that most languages require - one
list per language. We started with one character set per language and
used the clustering algorithm in order to join the character sets to
bigger.  The character sets described in files installed in the
directory
.I fontsets
were the result of the algorithm.
These files list the unicodes of the symbols of the character set, one
per line. Comments starting with a sharp sign are also allowed.

The files
.IR ascii.set ", " linux.set ", " freebsd.set " and " useful.set
contain four special character sets.  The first lists the ASCII
symbols and the second and the third list the symbols from the so
called alternate character set (see section "Line Graphics" of
.BR terminfo (5))
\- one for Linux and one for FreeBSD.  Notice that in order to limit
itself to the cp437 character set, the Linux console driver does some
approximations of the symbols from the alternate character set. For
example it prints U+256A (BOX DRAWINGS VERTICAL SINGLE AND HORIZONTAL
DOUBLE) instead of the not-equal sign. The file linux.set lists the
symbols used by the Linux console driver (i.e. U+256A instead of the
not-equal sign).  The symbols from freebsd.set are not fixed by the
FreeBSD kernel, but there too there are some approximations.

In most cases there is more available space in the fonts than
necessary. The spare codes can be filled with the symbols from the
.I useful.set
special character set.  It is convenient to use a colon before the
name of
.I useful.set
on the command line of
.B bdf2psf
so no warnings are issued when there is no space in the font for some
of these symbols.

.SH EQUIVALENCE FILES

The equivalence files define an equivalence relation between
unicodes. The sharp sign is used for comments, the empty lines are
ignored. All other lines should list two or more unicodes.  Only one
glyph will be allocated in the PSF font for these unicodes.

Example:

     U+2126 U+03A9
     # U+2126:   OHM SIGN
     # U+03A9:   GREEK CAPITAL LETTER OMEGA
     U+041D U+0048
     # U+041D:   CYRILLIC CAPITAL LETTER EN
     # U+0048:   LATIN CAPITAL LETTER H

This equivalence file says that U+2126 (the Ohm sign) and U+03A9
(Omega) have the same look so only one glyph is enough for them. And
also U+041D (Cyrillic En) and U+0048 (Latin H) look the same.

Two equivalence files are provided -
.I standard.equivalents
and
.I arabic.equivalents.
The first one can be used for all fonts.  The purpose of the second is
to reduce the number of the necessary glyphs for the Arabic letters at
the cost of the font quality.  It should be used only for fonts that
have to support Arabic but there is not enough space in the PSF font
for all Arabic characters.  The
.B Uni1
character set is a character set that requires
.I arabic.equivalents.

.SH FILES

All mentioned files and directories are usually installed in
.I /usr/share/bdf2psf
or
.I /usr/local/share/bdf2psf.

.SH AUTHOR
Anton Zinoviev <anton@lml.bas.bg>
